home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.2 Development Libraries / SGI IRIX 6.2 Development Libraries.iso / dist / complib.idb / usr / share / catman / p_man / cat3 / complib / zhsein.z / zhsein
Text File  |  1996-03-14  |  7KB  |  199 lines
  1.  
  2.  
  3.  
  4. ZZZZHHHHSSSSEEEEIIIINNNN((((3333FFFF))))                                                          ZZZZHHHHSSSSEEEEIIIINNNN((((3333FFFF))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ZHSEIN - use inverse iteration to find specified right and/or left
  10.      eigenvectors of a complex upper Hessenberg matrix H
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      SUBROUTINE ZHSEIN( SIDE, EIGSRC, INITV, SELECT, N, H, LDH, W, VL, LDVL,
  14.                         VR, LDVR, MM, M, WORK, RWORK, IFAILL, IFAILR, INFO )
  15.  
  16.          CHARACTER      EIGSRC, INITV, SIDE
  17.  
  18.          INTEGER        INFO, LDH, LDVL, LDVR, M, MM, N
  19.  
  20.          LOGICAL        SELECT( * )
  21.  
  22.          INTEGER        IFAILL( * ), IFAILR( * )
  23.  
  24.          DOUBLE         PRECISION RWORK( * )
  25.  
  26.          COMPLEX*16     H( LDH, * ), VL( LDVL, * ), VR( LDVR, * ), W( * ),
  27.                         WORK( * )
  28.  
  29. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  30.      ZHSEIN uses inverse iteration to find specified right and/or left
  31.      eigenvectors of a complex upper Hessenberg matrix H.
  32.  
  33.      The right eigenvector x and the left eigenvector y of the matrix H
  34.      corresponding to an eigenvalue w are defined by:
  35.  
  36.                   H * x = w * x,     y**h * H = w * y**h
  37.  
  38.      where y**h denotes the conjugate transpose of the vector y.
  39.  
  40.  
  41. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  42.      SIDE    (input) CHARACTER*1
  43.              = 'R': compute right eigenvectors only;
  44.              = 'L': compute left eigenvectors only;
  45.              = 'B': compute both right and left eigenvectors.
  46.  
  47.      EIGSRC  (input) CHARACTER*1
  48.              Specifies the source of eigenvalues supplied in W:
  49.              = 'Q': the eigenvalues were found using ZHSEQR; thus, if H has
  50.              zero subdiagonal elements, and so is block-triangular, then the
  51.              j-th eigenvalue can be assumed to be an eigenvalue of the block
  52.              containing the j-th row/column.  This property allows ZHSEIN to
  53.              perform inverse iteration on just one diagonal block.  = 'N': no
  54.              assumptions are made on the correspondence between eigenvalues
  55.              and diagonal blocks.  In this case, ZHSEIN must always perform
  56.              inverse iteration using the whole matrix H.
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ZZZZHHHHSSSSEEEEIIIINNNN((((3333FFFF))))                                                          ZZZZHHHHSSSSEEEEIIIINNNN((((3333FFFF))))
  71.  
  72.  
  73.  
  74.      INITV   (input) CHARACTER*1
  75.              = 'N': no initial vectors are supplied;
  76.              = 'U': user-supplied initial vectors are stored in the arrays VL
  77.              and/or VR.
  78.  
  79.      SELECT  (input) LOGICAL array, dimension (N)
  80.              Specifies the eigenvectors to be computed. To select the
  81.              eigenvector corresponding to the eigenvalue W(j), SELECT(j) must
  82.              be set to .TRUE..
  83.  
  84.      N       (input) INTEGER
  85.              The order of the matrix H.  N >= 0.
  86.  
  87.      H       (input) COMPLEX*16 array, dimension (LDH,N)
  88.              The upper Hessenberg matrix H.
  89.  
  90.      LDH     (input) INTEGER
  91.              The leading dimension of the array H.  LDH >= max(1,N).
  92.  
  93.      W       (input/output) COMPLEX*16 array, dimension (N)
  94.              On entry, the eigenvalues of H.  On exit, the real parts of W may
  95.              have been altered since close eigenvalues are perturbed slightly
  96.              in searching for independent eigenvectors.
  97.  
  98.      VL      (input/output) COMPLEX*16 array, dimension (LDVL,MM)
  99.              On entry, if INITV = 'U' and SIDE = 'L' or 'B', VL must contain
  100.              starting vectors for the inverse iteration for the left
  101.              eigenvectors; the starting vector for each eigenvector must be in
  102.              the same column in which the eigenvector will be stored.  On
  103.              exit, if SIDE = 'L' or 'B', the left eigenvectors specified by
  104.              SELECT will be stored consecutively in the columns of VL, in the
  105.              same order as their eigenvalues.  If SIDE = 'R', VL is not
  106.              referenced.
  107.  
  108.      LDVL    (input) INTEGER
  109.              The leading dimension of the array VL.  LDVL >= max(1,N) if SIDE
  110.              = 'L' or 'B'; LDVL >= 1 otherwise.
  111.  
  112.      VR      (input/output) COMPLEX*16 array, dimension (LDVR,MM)
  113.              On entry, if INITV = 'U' and SIDE = 'R' or 'B', VR must contain
  114.              starting vectors for the inverse iteration for the right
  115.              eigenvectors; the starting vector for each eigenvector must be in
  116.              the same column in which the eigenvector will be stored.  On
  117.              exit, if SIDE = 'R' or 'B', the right eigenvectors specified by
  118.              SELECT will be stored consecutively in the columns of VR, in the
  119.              same order as their eigenvalues.  If SIDE = 'L', VR is not
  120.              referenced.
  121.  
  122.      LDVR    (input) INTEGER
  123.              The leading dimension of the array VR.  LDVR >= max(1,N) if SIDE
  124.              = 'R' or 'B'; LDVR >= 1 otherwise.
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ZZZZHHHHSSSSEEEEIIIINNNN((((3333FFFF))))                                                          ZZZZHHHHSSSSEEEEIIIINNNN((((3333FFFF))))
  137.  
  138.  
  139.  
  140.      MM      (input) INTEGER
  141.              The number of columns in the arrays VL and/or VR. MM >= M.
  142.  
  143.      M       (output) INTEGER
  144.              The number of columns in the arrays VL and/or VR required to
  145.              store the eigenvectors (= the number of .TRUE. elements in
  146.              SELECT).
  147.  
  148.      WORK    (workspace) COMPLEX*16 array, dimension (N*N)
  149.  
  150.      RWORK   (workspace) DOUBLE PRECISION array, dimension (N)
  151.  
  152.      IFAILL  (output) INTEGER array, dimension (MM)
  153.              If SIDE = 'L' or 'B', IFAILL(i) = j > 0 if the left eigenvector
  154.              in the i-th column of VL (corresponding to the eigenvalue w(j))
  155.              failed to converge; IFAILL(i) = 0 if the eigenvector converged
  156.              satisfactorily.  If SIDE = 'R', IFAILL is not referenced.
  157.  
  158.      IFAILR  (output) INTEGER array, dimension (MM)
  159.              If SIDE = 'R' or 'B', IFAILR(i) = j > 0 if the right eigenvector
  160.              in the i-th column of VR (corresponding to the eigenvalue w(j))
  161.              failed to converge; IFAILR(i) = 0 if the eigenvector converged
  162.              satisfactorily.  If SIDE = 'L', IFAILR is not referenced.
  163.  
  164.      INFO    (output) INTEGER
  165.              = 0:  successful exit
  166.              < 0:  if INFO = -i, the i-th argument had an illegal value
  167.              > 0:  if INFO = i, i is the number of eigenvectors which failed
  168.              to converge; see IFAILL and IFAILR for further details.
  169.  
  170. FFFFUUUURRRRTTTTHHHHEEEERRRR DDDDEEEETTTTAAAAIIIILLLLSSSS
  171.      Each eigenvector is normalized so that the element of largest magnitude
  172.      has magnitude 1; here the magnitude of a complex number (x,y) is taken to
  173.      be |x|+|y|.
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.